gh-1763 Documentation guidelines: description of adding a submodule #1819
Conversation
doc/contributing/docs.rst
Outdated
| docs/style | ||
| docs/examples | ||
| docs/examples | ||
| docs/doc_infrastructure |
There was a problem hiding this comment.
давай выбирать какие-нибудь лаконичные адреса, типа infra или subprojects. И ещё, инфраструктурой часто называют другое: ВМ или контейнеры, приложения, сеть между ними.
| #. Update the ``.gitmodules`` file by adding a new ``[submodule ...]`` section, | ||
| for example: | ||
|
|
||
| .. code-block:: bash |
| path = modules/metrics | ||
| url = https://github.com/tarantool/metrics.git | ||
| #. In the ``/modules`` directory, add the new submodule: |
There was a problem hiding this comment.
./modules, потому что мы считаем от корня проекта, а не от /.
| The steps to do that is the following: | ||
|
|
||
| .. contents:: | ||
| :local: |
There was a problem hiding this comment.
а что значит :local:?
There was a problem hiding this comment.
https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents
local : flag (empty)
Generate a local table of contents. Entries will only include subsections of the section in which the directive is given. If no explicit title is given, the table of contents will not be titled.
There was a problem hiding this comment.
Круто, не знал про такую штуку.
|
|
||
| In case of the ``metrics`` submodule, the content source files are in the | ||
| ``/doc/monitoring`` directory of the submodule repository. In the final | ||
| documentation view, the content should appear in the `Monitoring <https://www.tarantool.io/en/doc/latest/book/monitoring/>`_ |
There was a problem hiding this comment.
Это могла бы быть ссылка через :doc:
|
|
||
| So, we need to: | ||
|
|
||
| * in ``/doc/book``of the documentation repository, create |
There was a problem hiding this comment.
не хватает пробела после book
|
|
||
| So, we need to: | ||
|
|
||
| * in ``/doc/book/cartridge``of the documentation repository, create |
There was a problem hiding this comment.
I think it can be explained in a more straightforward way:
- create a directory at
./doc/book/cartridge/cartridge_cli - copy
./modules/cartridge_cli/README.rstto./doc/book/cartridge/cartridge_cli/index.rst.
| We can take examples of the already existing submodules to show the logic of | ||
| the settings. | ||
|
|
||
| ``metrics`` |
There was a problem hiding this comment.
Очень круто, что ты разбираешь аж на двух примерах, как у нас всё устроено и почему именно так.
|
|
||
| .. code-block:: bash | ||
| monitoring_root="${project_root}/modules/metrics/doc/monitoring" # |
There was a problem hiding this comment.
решетка в конце строки не нужна )
There was a problem hiding this comment.
А вместо копирования кода можно было бы включить куски прямо из update_submodules.sh https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-literalinclude
| In this case, we need to add such a repository containing the source files | ||
| as a submodule to the `documentation repository <https://github.com/tarantool/doc>`_ | ||
| and set up other necessary settings to ensure the proper building of the entire | ||
| body of Tarantool documentation presented at the `official web-site <http://www.tarantool.io/en/doc>`_. |
There was a problem hiding this comment.
лучше https, и можно дать ссылку без языка, чтобы нужный язык выбрался сам: https://www.tarantool.io/doc
…tion infrastructure with the description of adding a submodule into the documentation repository. Closes #1763
NickVolynkin
force-pushed
the
veod32/gh-1763-guidelines-add-subproject
branch
from
fe57202 to
ed4f016
Compare
3 participants
Add a new section in the Documentation guidelines related to documentation infrastructure with the description of adding a submodule into the documentation repository.
Closes #1763